고급 사용자 지정

Congo를 수동으로 빌드하는 방법을 배우세요.

만약 추가 도움이 필요하다면 GitHub Discussions에 질문을 게시하세요.

Hugo 프로젝트 구조 #

먼저 빠른 참고로 Hugo 프로젝트 구조와 콘텐츠 및 테마 사용자 지정에 대한 최선의 방법을 살펴보세요.

콩고는 모든 표준 휴고 관행을 활용하도록 제작되었습니다. 핵심 테마 파일을 변경하지 않고도 테마의 모든 측면을 사용자 정의하고 재정의할 수 있도록 설계되었습니다. 이를 통해 웹사이트의 모양과 느낌을 완벽하게 제어하면서 원활하게 업그레이드할 수 있습니다

이를 달성하기 위해 테마 파일을 직접 수정하지 마세요. Hugo 모듈, git 하위 모듈 또는 수동으로 테마를 themes/ 디렉토리에 포함하는 경우, 이러한 파일을 절대 수정하지 마세요.

올바른 방법은 Hugo의 강력한 파일 조회 순서를 사용하여 파일을 재정의하는 것입니다. 요약하자면, 조회 순서는 프로젝트 디렉토리에 포함된 파일이 자동으로 테마 파일을 재정의함을 보장합니다.

예를 들어, 콩고의 기본 기사 템플릿을 재정의하고 싶다면, 간단히 프로젝트 루트에 layouts/_default/single.html 파일을 만들 수 있습니다. 이 파일은 테마 자체를 변경하지 않고도 테마의 single.html을 재정의합니다. 이 방법은 테마 파일 - HTML 템플릿, 부분, 커스텀 코드, 구성 파일, 데이터, 자산 등에 모두 적용됩니다.

이 간단한 관행을 따르면 테마를 업데이트할 때 (또는 다른 테마 버전 테스트) 사용자 지정 변경 사항을 잃지 않을 것입니다.

색 구성표 #

콩고는 기본 제공 색상 구성표를 제공합니다. 기본 색상 구성표를 변경하려면 colorScheme 테마 매개변수를 설정할 수 있습니다. 내장된 구성표에 대해 자세히 알아보려면 시작하기 섹션을 참조하세요.

기본 테마 외에도 나만의 테마를 만들어 웹사이트를 원하는 대로 재스타일링할 수 있습니다. 테마 구성표는 assets/css/schemes/ 폴더에 <scheme-name>.css 파일을 만들어 만듭니다. 파일을 만들면 테마 구성에서 이름으로 참조할 수 있습니다.

콩고는 테마 전체에서 사용되는 세 가지 색상 팔레트를 정의합니다. 세 가지 색상은 neutral, primary 및 secondary 변형으로 정의되며, 각각 색상의 열 가지 그라데이션을 포함합니다.

Tailwind CSS 3.0의 불투명도 값을 계산하는 방식 때문에 구성표에 지정된 색상은 특정 형식을 따라야 합니다. 즉, 빨간색, 초록색 및 파란색 색상 값을 제공해야 합니다.

:root {
  --color-primary-500: 139, 92, 246;
}

이 예제는 primary-500 색상에 대한 CSS 변수를 정의합니다. 빨간색 값은 139, 초록색 값은 92 및 파란색 값은 246입니다.

기존 테마 스타일시트 중 하나를 템플릿으로 사용합니다. 색상은 자유롭게 재정의할 수 있지만, 영감을 얻으려면 공식 Tailwind colour palette reference를 확인하세요.

스타일시트 재정의하기 #

가끔 자신의 HTML 요소를 스타일링하기 위해 사용자 지정 스타일을 추가해야 합니다. 콩고는 이 시나리오를 위해 자신의 CSS 스타일시트에서 기본 스타일을 재정의할 수 있도록 합니다. 간단히 프로젝트의 assets/css/ 폴더에 custom.css 파일을 만듭니다.

custom.css 파일은 Hugo에 의해 최소화되고 모든 다른 테마 스타일 뒤에 자동으로 로드되므로 사용자 지정 파일의 모든 것이 기본값을 재정의합니다.

폰트 크기 조정하기 #

웹사이트의 폰트 크기를 변경하는 것은 기본 스타일시트를 재정의하는 한 가지 예입니다. 콩고는 테마 전체에서 크기가 조정된 폰트 크기를 사용하므로 기본 HTML 폰트 크기에서 파생됩니다. 기본적으로 Tailwind는 기본 크기를 12pt로 설정하지만 원하는 값으로 변경할 수 있습니다.

위에서 설명한 지침을 따라 custom.css 파일을 만들고 다음 CSS 선언을 추가합니다.

/* 기본 폰트 크기 증가 */
html {
  font-size: 13pt;
}

이 하나의 값을 변경하면 웹사이트의 모든 폰트 크기가 이 새로운 크기와 일치하도록 조정됩니다. 따라서 전체 폰트 크기를 증가시키려면 값을 12pt보다 크게 만듭니다. 마찬가지로, 폰트 크기를 감소시키려면 값을 12pt보다 작게 만듭니다.

소스에서 테마 CSS 빌드하기 #

만약 주요 변경이 필요하다면, Tailwind CSS의 JIT 컴파일러를 활용하여 테마 CSS를 처음부터 다시 빌드할 수 있습니다. 이는 Tailwind 구성을 조정하거나 기본 스타일시트에 추가 Tailwind 클래스를 원하는 경우에 유용합니다.

Tailwind CSS를 빌드하는 방법을 단계별로 살펴보겠습니다.

Tailwind 구성 #

실제로 사용되는 Tailwind 클래스만 포함하는 CSS 파일을 생성하기 위해 JIT 컴파일러는 모든 HTML 템플릿과 Markdown 콘텐츠 파일을 스캔해야 합니다. 컴파일러는 테마 디렉토리의 루트에 있는 tailwind.config.js 파일을 참조하여 이 작업을 수행합니다.

// themes/congo/tailwind.config.js

module.exports = {
  content: [
    "./layouts/**/*.html",
    "./content/**/*.{html,md}",
    "./themes/congo/layouts/**/*.html",
    "./themes/congo/content/**/*.{html,md}",
  ],

  // and more...
};

이 기본 구성은 특정 프로젝트 구조를 따르면 쉽게 자신의 CSS 파일을 생성할 수 있도록 포함되어 있습니다. 즉, 프로젝트에 Congo를 themes/congo/ 하위 디렉토리로 포함해야 합니다. 이는 테마를 설치하기 위해 Hugo 모듈을 쉽게 사용할 수 없으며, 대신 git 서브모듈(권장) 또는 수동 설치 경로를 따라야 합니다. 설치 문서는 이 방법들을 설명합니다.

프로젝트 구조 #

기본 구성을 활용하기 위해 프로젝트는 다음과 같아야 합니다…

.
├── assets
│   └── css
│       └── compiled
│           └── main.css  # 이 파일을 생성할 것입니다
├── config  # 사이트 구성
│   └── _default
├── content  # 사이트 콘텐츠
│   ├── _index.md
│   ├── projects
│   │   └── _index.md
│   └── blog
│       └── _index.md
├── layouts  # 사이트 사용자 지정 레이아웃
│   ├── partials
│   │   └── extend-article-link.html
│   ├── projects
│   │   └── list.html
│   └── shortcodes
│       └── disclaimer.html
└── themes
    └── congo  # git 서브모듈 또는 수동 설치

이 예제 구조는 새로운 projects 콘텐츠 유형과 해당 커스텀 레이아웃, 커스텀 쇼트코드 및 확장된 부분을 추가합니다. 프로젝트가 이 구조를 따르면 필요한 것은 main.css 파일을 다시 컴파일하는 것뿐입니다.

의존성 설치 #

이 작업을 수행하려면 themes/congo/ 디렉토리로 변경하고 프로젝트 의존성을 설치해야 합니다. 이 단계에서는 npm이 필요합니다.

cd themes/congo
npm install

Tailwind 컴파일러 실행 #

의존성이 설치되면 Tailwind CLI를 사용하여 JIT 컴파일러를 호출할 수 있습니다. 프로젝트의 루트로 돌아가서 다음 명령을 실행하세요:

cd ../..
./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit

경로가 관여되어 있지만 사실상 Tailwind CLI를 호출하고 Tailwind 구성 파일(위에서 살펴본 파일)의 위치, 테마의 main.css 파일을 찾을 위치 및 컴파일된 CSS 파일을 배치할 위치(프로젝트의 assets/css/compiled/ 폴더)를 전달합니다.

구성 파일은 프로젝트의 모든 콘텐츠와 레이아웃을 자동으로 검사하고 테마의 모든 것과 함께 새로운 CSS 파일을 빌드합니다. Hugo가 파일 계층 구조를 처리하는 방식 때문에 이 파일은 이제 테마에서 오는 파일을 자동으로 재정의합니다.

새로운 Tailwind CSS 스타일을 필요로 하는 레이아웃 변경 사항을 만들 때마다 간단히 명령을 다시 실행하고 새로운 CSS 파일을 생성할 수 있습니다. 또한 명령의 끝에 -w를 추가하여 JIT 컴파일러를 모니터링 모드로 실행할 수 있습니다.

빌드 스크립트 만들기 #

이 솔루션을 완전히 완료하려면 이러한 명령에 대한 별칭을 만들거나 루트에 package.json 파일을 추가하여 필요한 스크립트를 포함할 수 있습니다…

// package.json

{
  "name": "my-website",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "server": "hugo server -b http://localhost -p 8000",
    "dev": "NODE_ENV=development ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
    "build": "NODE_ENV=production ./themes/congo/node_modules/tailwindcss/lib/cli.js -c ./themes/congo/tailwind.config.js -i ./themes/congo/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
  },
  // and more...
}

이제 사이트를 디자인하려면 npm run dev를 호출하고 컴파일러가 모니터링 모드로 실행됩니다. 배포를 준비하려면 npm run build를 실행하고 깨끗한 Tailwind CSS 빌드를 얻을 수 있습니다.

🙋‍♀️ 도움이 필요하다면 GitHub Discussions에 질문을 게시하세요.